BMUG PD-ROM A/PD-ROM A.iso/Utility/Text/UUTool/uu engine/UUGlue.h

Text File | 1991-06-12 | 7.3 KB | 265 lines | [TEXT/KAHL]

/*
**    Project:    uu**code engine
**    Author:        Bernhard S. Wieser
**    Module:        uuglue
**    Date:        5/19/91
**    Revised:    6/1/91        L.R. suggested user allocate buffers
**                6/8/91        L.R. suggested Pascal calling conventions
**                            - removed table/engine globals
**    Version:    1.0.2
**
**    Preface:
**        uu**code engine is © by Bernhard S. Wieser and Octavian Micro
**    development, all rights reserved.  Please read the accompanying
**    licensing agreement before use.
**
**    Purpose:
**        This code should be compiled with the program using the
**    uu**coding engine.  It loads and unloads the resource, as well as
**    providing 'glue' to the contained routines.
**        The 'glue' routines bind the various uu**coding functions
**    contained in the resource file to known subroutines names, thus
**    providing a means of easy access from a high level language.
**    The underlying resource routines use the Pascal calling convention.
**        The resources occupy <3K of memory.  You must make room for
**    the buffers, except for the uuencode() and uudecode() routines which
**    require that you specify how much (contiguous) space they will allocate.
**        To be safe (especially with noxious INITs which invade an
**    applications memory), allocate at least (volume buffer size)
**    524 bytes + some so as not to unexpectedly run out of memory.
**
**    Conditions of use:
**        Visible credit to Bernhard S. Wieser and Octavian Micro
**    Development MUST be given.  Written permission MUST be obtained
**    upon any distribution, with a licensing fee pending depending on what
**    it is used for.
**
**    Algorithm:
**        uuencoding takes 24 bit from input stream (3 bytes) and splits
**    it into 32 bits (4 bytes) output.  Each output byte has the top 2
**    bits clear, and can be translated into a printable character.  The
**    traditional way is to simply add $20 (space).  uudecoding simply
**    subtracts $20, strips the top 2 bits from input, and stuffs things
**    back together.
**        The encoding engine uses a translate table. Two reasons.
**    First, its faster than bit manipulation.  Second, I can avoid
**    some characters (like space, which some mailers despise).  This
**    table can be changed so long as the character, when its top 2
**    bits are stripped, equals its index into the table.
**
**        Example:
**                  '`' = $60,    ' ' = $20    <- encoded
**                  AND    $3F              $3F
**                          ___              ___
**                        $20              $20
**                  SUB    $20              $20
**                          ___              ___
**                        $00              $00    <- decoded
**
**    Data Structures:
**        Here is the resource 'UENG' 128 jump table:
**                OFFSET    CODE
**                   0    BRA    encode
**                  +4    BRA    encodeOne
**                  +8    BRA    encodeLine
**                  +C    BRA    uuencode
**                 +10    BRA    decode
**                 +14    BRA    decodeOne
**                 +18    BRA    decodeLine
**                 +1C    BRA    uudecode
**
**        Resource 'HEXA' 128 is an array of 64 printable characters
**        which equal their index when the top two bits are stripped.
**
**    Revisions
**        User must now maintain the table and engine handles.  User
**    Must also remember these are LOCKED so must be dereferenced and
**    passed as pointers to the core routines.
*/

/*
**    Load and Unload of uu**engine
*/
pascal OSErr UULoad(
    Handle *,    /* pointer to the handle of returned look-up table */
    Handle *    /* pointer to the handle of returned engine base address */
    );
pascal void UUnload(
    Handle,        /* handle to the look-up table */
    Handle        /* handle to the engine base address */
    );

/*                                    **
**    The core Pascal glue routines!    **
**                                    */

/*
**    encodeOne
**        Encode one byte only, only use low 6 bits input.
**
**    Parameters
**        c        the character (passed as integer)
**        table    pointer to the encode table
**        engine    pointer to the engine base
**
**    Returns
**        the encoded character (as integer)
*/
pascal short encodeOne(
    short,
    Ptr,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x0004 };

/*
**    encode
**        Take three bytes input, return four bytes uucoded output.
**
**    Parameters
**        three    pointer to an array holding at least three characters
**        table    pointer to the encode table
**        engine    pointer to the engine base
**
**    Returns
**        four characters of encoded data in a long word
*/
pascal OSType encode(
    void *,
    Ptr,
    Ptr
    ) = { 0x205F, 0x4E90 };

/*
**    encodeLine
**        Take 'insize' bytes from buffer 'in' and encode to buffer 'out'.
**    The size of the encode data is returned (including length and CR).
**    Remember, input buffer should be divisible by 3, and output size
**    will be 4 times the quotient (plus 2 for length and CR).
**
**    Parameters
**        in        pointer to input buffer
**        insize    size of input buffer
**        out        pointer to output buffer
**        table    pointer to the encode table
**        engine    pointer to the engine base
**
**    Returns
**        length of encoded data in output buffer
*/
pascal long encodeLine(
    void *,
    int,
    void *,
    Ptr,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x0008 };

/*
**    uuencode
**        Encode file 'infile' to output file 'outfile', calling
**    'routine' as buffers are flushed.  'routine' should be NULL
**    if there are no periodic tasks to perform.  'numbufrs' tells the
**    engine how many input/output buffers to allocate.  An input
**    buffer is 45 bytes long, and output buffer is 62 bytes long.
**    Example, numbufrs = 1024 would allocate 45K+62K = 107K.
**
**    Parameters
**        infile        input file's file reference number
**        outfile        output file's "        "        "
**        numbufrs    number of i/o buffers to use (not size of!)
**        routine        update procedure pointer (or NIL)
**        table        pointer to the encode table
**        engine        pointer to the engine base
**
**    Returns
**        any error encountered
*/
pascal OSErr uuencode(
    int,
    int,
    int,
    void *,
    Ptr,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x000C };

/*
**    decodeOne
**        Decode one coded character.
**
**    Parameters
**        c        encoded character (integer passed)
**        engine    pointer to the engine's base address
**
**    Returns
**        the decoded character (integer)
*/
pascal short decodeOne(
    short,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x0014 };

/*
**    decode
**        Decode 4 bytes to 3.
**
**    Parameters
**        s    pointer to 4 byte array of data to decode
**        engine    pointer to the engine's base address
**
**    Returns
**        the decoded data (in the upper 8 bits of a long word)
*/
pascal OSType decode(
    void *,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x0010 };

/*
**    decodeLine
**        Decode a uucoded input in 'in' to buffer 'out'.  Returns
**    length of decoded data.
**
**    Parameters
**        in        pointer to an input buffer, of which first encoded
**                character is buffer length
**        out        pointer to the buffer to contained decoded data,
**                generally < 80 bytes is required.
**        engine    pointer to the engine's base address
**
**    Returns
**        the amount of decoded data (or buffer size if you like)
*/
pascal long decodeLine(
    void *,
    void *,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x0018 };

/*
**    uudecode
**        Decode 'infile' to 'outfile', calling 'routine' on buffer flush.
**    'bufsizes', unlike in uuencode, is the actual buffer size in bytes
**    that you want to allocated for input and output buffers.
**  NEVER allocate a buffer less than 10 bytes (it would be very silly).
**    Suggested values are multiples of 524 bytes.
**    Function returns error.
**
**    Parameters
**        infile        file reference number of input (encoded) data
**        outfile        "        "        "      of output (decoded) data
**        bufsizes    the size in bytes for input and output buffers
**                    to be allocated by uudecode()
**        routine        the update procedure (or NIL if none)
**        engine        pointer to the engine's base address
**
**    Returns
**        any errors encountered
*/
pascal OSErr uudecode(
    int,
    int,
    long,
    void *,
    Ptr
    ) = { 0x205F, 0x4EA8, 0x001C };